Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

NS_DEV_DOCFOR:objc_class:PrintPanel;,PrintPanel

Inherits From:	Panel : Window : Responder : Object

Declared In:	appkit/PrintPanel.h

Class Description

PrintPanel is a type of Panel that queries the user for information about a print job, such as which pages and how many copies to print.  The PrintPanel is created, displayed, and run (in a modal loop) when a printPSCode: message is sent to a View or Window, provided that the sender of the message doesn't implement the shouldRunPrintPanel: method to return NO (if the method isn't implemented, or if it returns YES, the Panel is brought up).

Each application can have but one PrintPanel object.  If you're creating a subclass of PrintPanel, you should send your subclass' class object a new message (without invoking alloc or allocFromZone:) before any printPSCode: messages are sent to ensure that an instance of your subclass is the unique PrintPanel object for your application.  

Short of subclassing PrintPanel, you can augment it's display by adding a custom View through the setAccessoryView: method.  The Print panel is automatically resized to accommodate the View that you add.  Note, however, that you don't have to create controls for special printer features.  If a printer includes features in the ªOpenUIº field of its PostScript Printer Description (PPD) table, these features will be displayed in a separate panel that's brought up when the user clicks the Print panel's Options button. 

The Print panel lists the names of the printers that are available for printing.  If only one printer is available, the list isn't displayed.

Instance Variables

id appIcon;

id pageMode;

id firstPage;

id lastPage;

id copies;

id ok;

id cancel;

id preview;

id save;

id printers;

id feed;

id resolutionList;

id name;

id note;

id status;

int exitTag;

id accessoryView;

id buttons;

id optionsButtons;

appIcon 	The Button containing the application's icon.

pageMode 	The Matrix of radio buttons indicating whether to print all pages or a subset.

firstPage 	The Form indicating the first page to print.

lastPage 	The Form indicating the last page to print.

copies 	The TextField indicating how many copies to print.

ok 	The Print Button.

cancel 	The Cancel Button.

preview 	The Preview Button.

save 	Save Button.

printers 	The Matrix of available printers.

feed 	The PopUpList of paper feed options.

resolutionList 	The PopUpList of resolution choices.

name 	The TextField for the name of the currently chosen printer.

note 	The TextField for the note for the currently chosen printer.

status 	The TextField for the status of the requested operation.

exitTag 	The tag of the button the user clicked to exit the panel.

accessoryView 	The optional View added by the application.

buttons	The Matrix of Print panel buttons.

optionsButton	The Matrix of Options panel buttons.

Method Types

Creating and freeing a PrintPanel
+ new
+ newContent:style:backing:buttonMask:defer:
- free

Customizing the PrintPanel	- setAccessoryView:
- accessoryView

Running the panel	- runModal
- pickedButton: 

Updating the panel's display	- pickedAllPages: 
- textWillChange:

Communicating with the PrintInfo object
- updateFromPrintInfo 
- finalWritePrintInfo

Class Methods

NS_DEV_DOCFOR:objc_method:[PrintPanel-alloc];,alloc

Generates an error message.  This method cannot be used to create PrintPanel instances; use new instead.

NS_DEV_DOCFOR:objc_method:[PrintPanel-allocFromZone:];,allocFromZone:

Generates an error message.  This method cannot be used to create PrintPanel instances; use new instead.

NS_DEV_DOCFOR:objc_method:[PrintPanel-new];,new

+ new

Returns the application's sole PrintPanel object, creating it if necessary.  You rarely need to invoke this method directly; the PrintPanel object is created automatically when printPSCode: is sent to a View or Window. 

NS_DEV_DOCFOR:objc_method:[PrintPanel-newContent:style:backing:buttonMask:defer:];,newContent:style:backing:buttonMask:defer:

+ newContent:(const NXRect *)contentRect
style:(int)aStyle
backing:(int)bufferingType
buttonMask:(int)mask
defer:(BOOL)flag

Initializes the PrintPanel object.  You never invoke this method; use new instead.

Instance Methods

NS_DEV_DOCFOR:objc_method:[PrintPanel-accessoryView];,accessoryView

- accessoryView

Returns the PrintPanel's accessory view.

See also:  - setAccessoryView:

NS_DEV_DOCFOR:objc_method:[PrintPanel-finalWritePrintInfo];,finalWritePrintInfo

- finalWritePrintInfo

Writes the values of the PrintPanel's printing attributes to the application's PrintInfo object.

See also:  - updateFromPrintInfo

NS_DEV_DOCFOR:objc_method:[PrintPanel-free];,free

- free

Frees the PrintPanel object and its contents, including the accessory view.

NS_DEV_DOCFOR:objc_method:[PrintPanel-pickedAllPages:];,pickedAllPages:

- pickedAllPages:sender

The target of the Pages radio buttons, this method updates the text that's displayed in the From and To (pages) fields.  By default, the fields are empty if the All radio button is clicked and set to ªfirstº and ªlastº if the From/To button is clicked.  These strings can only be changed by overriding this method. 

NS_DEV_DOCFOR:objc_method:[PrintPanel-pickedButton:];,pickedButton:

- pickedButton:sender

The target of the Print, Cancel, Preview, Save, and Fax buttons, this method ends the Print panel's modal run.  If a button other than Cancel inspired this method, then the Print panel's Copies field and the From and To (pages) fields must be acceptable (they must hold positive numbers), otherwise the unacceptable entry is selected and the panel isn't stopped.   If the panel is being cancelled, it's stopped regardless of the entries' acceptability.  Upon successful dismissal, the exitTag instance variable is set to the tag of the button that the user clicked to dismiss the panel (NX_OKTAG, NX_CANCELTAG, NX_PREVIEWTAG, NX_SAVETAG, or NX_FAXTAG).  

NS_DEV_DOCFOR:objc_method:[PrintPanel-runModal];,runModal

- (int)runModal

Reads the pertinent data from the PrintInfo object into the PrintPanel object and then runs the Print panel in a modal loop.  When the user clicks one of the buttons at the bottom of the panel (Print, Cancel, Preview, Save, or Fax), the modal loop is broken (by the pickedButton: method) and, if user didn't cancel the panel, the new Print information is written to the PrintInfo object.  This method returns the tag of the button that the user clicked to dismiss the panel (NX_OKTAG, NX_CANCELTAG, NX_PREVIEWTAG, NX_SAVETAG, or NX_FAXTAG).

This method is normally invoked from Window or View's printPSCode: method.  You should note that the feat that's requested by the user (printing, faxing, etc.) is performed by printPSCode:.  Furthermore, this method doesn't hide the Print panel after the modal loop is broken; that, too, is left to printPSCode:.

NS_DEV_DOCFOR:objc_method:[PrintPanel-setAccessoryView:];,setAccessoryView:

- setAccessoryView:aView

Adds aView to the PrintPanel's view hierarchy.  Applications can invoke this method to add a View that contains their own controls.  The panel is automatically resized to accommodate aView.  This method can be invoked repeatedly to change the accessory view depending on the situation.  If aView is nil, then the panel's current accessory view, if any, is removed.  Returns the old accessory View.

See also:  - accessoryView

NS_DEV_DOCFOR:objc_method:[PrintPanel-textWillChange:];,textWillChange:

- (BOOL)textWillChange:textObject

Inovoked when the user types in the From or To (pages) fields, this method ensures that the correct Pages radio button is selected (From/To rather than All).  If the To value is greater than the From value, the PrintInfo object will be set to print pages in reverse order.

NS_DEV_DOCFOR:objc_method:[PrintPanel-updateFromPrintInfo];,updateFromPrintInfo

- updateFromPrintInfo

Reads the application's PrintInfo object, setting the initial values of this panel.  This method is invoked automatically when the PrintPanel receives a runModal message.  

See also:  - finalWritePrintInfo